home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 1995 #5 & #6 / Amiga Plus CD - 1995 - No. 5 and 6.iso / pd / serien / purity / nr.51 / xpk / docs / sublibs.doc < prev    next >
Text File  |  1995-08-27  |  3KB  |  63 lines
  1. Some remarks for sublib writers
  2. -------------------------------
  3.  
  4. Most important: Talk to me. I'll check your libs and help you where needed.
  5. My address: umueller@amiga.physik.unizh.ch
  6.  
  7. How XpkPackChunk works:
  8. - Check xpar->Sub[0]. If it's 0, this is the first call. Allocate your tables
  9.   and store pointers to them in Sub[0] .. Sub[3].
  10. - Read xpar->InLen bytes from xpar->InBuf and pack them to xpar->OutBuf.
  11.   Don't exceed xpar->OutBufLen. Store packed len in xpar->OutLen.
  12.  
  13. How XpkUnpackChunk works:
  14. - Check xpar->Sub[0]. If it's 0, this is the first call. Allocate your tables
  15.   and store pointers to them in Sub[0] .. Sub[3].
  16. - Read xpar->InLen bytes from xpar->InBuf and unpack them to xpar->OutBuf.
  17.   Don't exceed xpar->OutBufLen. Maybe compare uncompressed len with 
  18.   xpar->OutLen.
  19.  
  20. Other notes:
  21. - Your library should, of course, be re-entrant. This means no PC-relative
  22.   addressing of writeable data. Whatever you have, store a pointer to it
  23.   somewhere in the XpkSubMessage. You can detect the first chunk of a file
  24.   by the fact that this pointer is still NULL. In case your lib is
  25.   not re-entrant, return XPKERR_LIBINUSE when required.
  26.  
  27. - There will be no larger chunks on (de)compression than the first one.
  28.  
  29. - On compression, you may expand the data by XPK_MARGIN bytes maximum. This
  30.   means the output buffer is as large as the input buffer plus XPK_MARGIN.
  31.   Compression libs would, of course, already return XPKERR_EXPANSION if
  32.   they exceed the input buffer.
  33.  
  34. - You must supply a function XpkPackReset, which clears all tables so
  35.   that the next chunk will be able to be unpacked independently. You also
  36.   have to call it before returning XPKERR_EXPANSION!
  37.  
  38. - On decompression, you will also have a XPK_MARGIN byte saftey margin for
  39.   runaway unpacking. 
  40.  
  41. - Fill in one XINFO structure. See libraries/xpksub.h for the meanings of
  42.   the fields therein.
  43.  
  44. - If your packer has only one packing mode, fill in one XMINFO structure 
  45.   (see xpk.h). Set the 'Upto' field to 100, this means this struct handles 
  46.   all modes up to (and including) 100, which is the max packing mode. Place
  47.   a pointer to this struct in the XINFO structure.
  48.  
  49. - There must be at least one XMINFO structure, and the last XMINFO 
  50.   structure must have the Upto set to 100. It must!
  51.  
  52. - If your packer has several modes, create several XMINFO structures and
  53.   sort them by efficiency in ascending order. Place a pointer to them
  54.   in XINFO. Set the XPKIF_MODES flag in the Flag field of XINFO.
  55.  
  56. - Your packer will get the 0..100 number and is responsible of mapping
  57.   it to its own packing modes.
  58.  
  59. - Set the DefMde field to some 0...100 number.
  60.  
  61. - If XSF_STEPDOWN is set in the Flags field of the SubParams structure,
  62.   you are allowed to reduce packing efficiency in order to save mem.
  63.